Role

Modified on 2012/01/20 20:59 by John Categorized as Roles
===Role Overview===
A 'Role' is a first class [workflow|workflow object] within Jetfire.  Roles provide the logged-in user with permissions for accessing workflows, workspace contents, executing methods, accessing properties and changing permissions.

A Jetfire [user] can be assigned one or more roles. Methods and properties objects can have roles assigned using the [access construct|'access construct'].  Workflow objects can be assigned roles programmatically (see below). This restricts usage and visibility of methods, properties to the Jetfire user by [dynamic access modifier|dynamically changing access modifiers]. Roles work on workflows by restricting access (not allowing workflows to be loaded into the cache of the [client nexus]).  The access rights are enforced through soft mechanisms in the client and rigorously enforced by the [server nexus].

Jetfire also uses roles internally to control all system functionality.

  Role(s) can give a Jetfire [user] special abilities with the Jetfire system such as:

# The ability to execute methods that have been declared with the 'access' construct.
# The ability to set and get properties that have been declared with the 'access' construct.
# The ability to set a property that otherwise has private getter and public setter.
# Restricting access to [workspace|workspaces] (and their objects) when the workspace workflow has had its 'Access Control List' set.
# Restricting access to workflow(object) when its 'Access Control List' set.

Roles can be identified by a unique name which must be assigned to the role when it is created.   Once created the name of role may not change.

In order for the user to have these special abilities a role of the user must match a member of the 'Access Control List' of the Jetfire object.

{TOC}

[anchor|#Creating A Role]
===Creating a Role===
A Jetfire Role can be created programatically just like [workflow#Creating A Jetfire Workflow Object|creating any workflow object].  A Role can be created by 2 techniques.
* Jetfire script using the 'new' operator.
* A Role workflow object can be created using the .net API. 

====Jetfire 'new' Operator ====
(((
{{
namespace NewRoleExample {BR}
{ 
:public workflow Factory
:{ {BR}
::  // A method that creates a new Role object.{BR}
::  public Role CreateRole(string roleName){BR}
:: {{BR}
::: // the new operator creates a new instance
::: // of a Role object;
::: return new Role(roleName);{BR}
:: } {BR}
:} {BR}
}{BR}
}})))

 
====New Workflow Object using the Jetfire API====

===Assigning A Role To A User===
see [User#Creating a User with a Role|Creating a User with a Role]

===Assigning A Role To a Method or Property===
A role can be assigned to a method or property using the [access construct|'access' construct].
((({{
      // The 'Approve' method can only be executed if the user has {BR}
      // the role 'Approver', otherwise the method will be 'private'.{BR}
      public void Approve(): access(""Approver""){BR}
      {{BR}
::         status = ""approved"";{BR} 
      }{BR}
 }}         
)))
====Request Approval====
This examples uses roles to build a very simple "Approval" workflow.  The login user Joe is allowed to execute the "Approve" method because he has the "Approver" role.  The Guest user can execute the "Approve" method because that user has no roles.
* [http://www.codeplex.com/Jetfire/Wiki/View.aspx?title=Request%20Approval&referringTitle=C-Sharp%20Examples|Approval Example]

====Advanced Request Approval====
This advanced example employs both states and roles in an request approval workflow.  The 'state' of workflow ensures once a method is 'approved' that it can not be 'declined' at later date.  The [role]s determine which users can 'approve' the request.{BR}
*[http://www.codeplex.com/Jetfire/Wiki/View.aspx?title=Advanced%20Request%20Approval&referringTitle=C-Sharp%20Examples|Request Approval Example]


===Assigning A Role to a Workspace===
====Departmental Request Approval Example====
In this example each department has a separate workspace where request workflows are stored.  The [workspace|workspaces] provide a firewall between departments not allowing members from one department to view another department's requests. Request workflows are approved when a user with the 'Approver' role, which is typically restricted to the department manager, executes the 'Approve' method of the request workflow.
*[http://jetfire.codeplex.com/Wiki/View.aspx?title=Department%20Request%20Approval%20Example&referringTitle=C-Sharp%20Examples|Departmental Request Approval Example ]
[anchor|#Assigning a role to a workflow]

[anchor|#rolesToworkflowprogrammatically]
===Assigning A Role to a Workflow Programmatically===
Roles can be assigned to an individual workflow restricting access to [user|users] with that role.  This is shown in the following example.

Note: Roles can also be assigned to "[workspace|workspaces]" effectively giving all the workflows in the workspace the access rights of the workspace.
(((
{{
namespace AddingRoleExample{br}
          {{br}
:              workflow MyFlow{br}
:              {{br}
::                 Flow flow;{br}
::                 Role role;{br}
::                  User user;{br}
::// Create a workflow with restricted access.  
::// Also create a 'user' that can access the new workflow.
::                  public Create(){br}
::                  {
:::                    flow = new Flow();{br}
:::                    role = new Role(""Manager"");{br}
:::                     workflow.AddAccessRole(flow, role);{br}
:::// add the role to the user named "ManagerUser". {br}
:::                     user = new User(""ManagerUser"");
:::                     user.AddRole(role);{br}
::                 }{br}
:              }{br}
:            workflow Flow{br}
:              {{br}
:: // add code for the workflow here.
:                }{br}
            }{br}
)))
}}

===See Also===
* [Jetfire Data Model]
Meta Keywords:
Meta Description:
Change Comment: